Allocates memory in the heap for a string, copies its contents, and produces a handle for the heap version of the string.

StringHandle NewString (
    ConstStr255Param theString
);

theString

A Pascal string that you want copied onto the heap.

function result

A handle to the newly allocated string. If the string cannot be allocated, NewString returns NULL. The size of the allocated string is based on the actual length of theString, which may not be 255 bytes.

DISCUSSION

Before using Pascal string functions that can change the length of the string, it is a good idea to maximize the size of the string object on the heap. You can call either the SetString function or the Memory Manager function SetHandleSize to modify the string’s size.

SPECIAL CONSIDERATIONS

NewString may move memory; your application should not call this function at interrupt time.

AVAILABILITY

Supported in Carbon. Available in CarbonLib 1.0 and later when InterfaceLib 7.1 or later is installed. Exported by CarbonLib 1.0 and later and by InterfaceLib 7.1 and later.

© 2000 Apple Computer, Inc. — (Last Updated 4/14/2000)